Rework of the generator guide #6889
Conversation
WalkthroughThe updates focus on documentation improvements and linting configuration enhancements. Documentation instructions now explicitly adopt the Diataxis framework, providing separate, detailed guidance for task-oriented guides and understanding-oriented topics. A generator creation guide was thoroughly rewritten with expanded steps, examples, and clearer structure. Vale linter configurations were updated with new exceptions for sentence casing and spelling. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
github-actions
bot
added
type/documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
.vale/styles/spelling-exceptions.txt (1)
164-165: Consider keeping the list strictly alphabetical for faster lookupNew entries are appended at the end. For long exception lists it’s easier to maintain if items stay in case-insensitive alphabetical order. Inserting “AI/IDE”-style terms in the correct place reduces future merge noise.
.vale/styles/Infrahub/sentence-case.yml (1)
86-87: Insert new exceptions in sorted order
AIandIDEdrop to the bottom of the list, breaking the existing A→Z flow (seeAlpha,Ansible,API, … earlier). Re-sorting now avoids later churn when another contributor runs an auto-sort.- Alpha + - AI - Ansible - API … - UI - Vale - VS Code extensions - WebUI - - IDE - - AI + - IDE.github/instructions/documentation.instructions.md (1)
45-52: Minor wording tweak for consistencyLine 48 mixes “conditional imperatives” with an imperative example that isn’t conditional. Consider rephrasing to keep examples parallel, e.g. “If you want X, do Y. If you need W, do Z.”
docs/docs/guides/generator.mdx (2)
7-8: Drop the redundant H1 headerDocusaurus renders the page title from front-matter; leaving the
# How to create a generator …heading produces a duplicate H1.-# How to create a generator in Infrahub
41-46: Avoid repetition of “locally”The word appears twice in two consecutive bullets; trimming one keeps the checklist crisp.
- - [infrahubctl]($(base_url)infrahubctl/infrahubctl) installed and configured locally - - The repository cloned locally where you'll develop the generator + - [infrahubctl]($(base_url)infrahubctl/infrahubctl) installed and configured on your workstation + - The repository cloned where you'll develop the generator
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.github/instructions/documentation.instructions.md(5 hunks).vale/styles/Infrahub/sentence-case.yml(1 hunks).vale/styles/spelling-exceptions.txt(1 hunks)docs/docs/guides/generator.mdx(2 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
docs/docs/guides/**/*.{md,mdx}
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Write guides in
docs/docs/guides/
Files:
docs/docs/guides/generator.mdx
docs/**/*.mdx
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Use Docusaurus markdown/MDX features in documentation
Files:
docs/docs/guides/generator.mdx
docs/**/*
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Develop documentation in
docs/, preview withinvoke docs.build docs.serve, and validate withinvoke docs.validate
Files:
docs/docs/guides/generator.mdx
🧠 Learnings (2)
.github/instructions/documentation.instructions.md (6)
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to docs/docs/guides/**/*.{md,mdx} : Write guides in docs/docs/guides/
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Documentation generated for Infrahub must reflect its novel approach, providing clarity around new concepts and demonstrating integration with familiar patterns from existing tools like Git, infrastructure-as-code, and CI/CD pipelines
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to docs/**/*.mdx : Use Docusaurus markdown/MDX features in documentation
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to docs/docs/reference/**/*.{md,mdx} : Write reference documentation in docs/docs/reference/
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to docs/**/* : Develop documentation in docs/, preview with invoke docs.build docs.serve, and validate with invoke docs.validate
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to {CONTRIBUTING.md,SECURITY.md} : See CONTRIBUTING.md and SECURITY.md at repo root for policies
docs/docs/guides/generator.mdx (2)
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Documentation generated for Infrahub must reflect its novel approach, providing clarity around new concepts and demonstrating integration with familiar patterns from existing tools like Git, infrastructure-as-code, and CI/CD pipelines
Learnt from: CR
PR: opsmill/infrahub#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to docs/docs/guides/**/*.{md,mdx} : Write guides in docs/docs/guides/
🪛 LanguageTool
docs/docs/guides/generator.mdx
[style] ~46-~46: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...figured locally - The repository cloned locally where you'll develop the generator ## ...
(ADVERB_REPETITION_PREMIUM)
🔇 Additional comments (2)
docs/docs/guides/generator.mdx (2)
351-359: Confirm.infrahub.ymlkey names
targets:usually expects a list;parameters:commonly maps filter names directly (name__value: ...) rather than wrapping them in aname:key. Please double-check against the current spec to avoid runtime schema errors.
328-341: Verify availability ofself.nodeswhenconvert_query_response: trueWith
convert_query_responseenabled, some SDK versions expose typed objects viaself.resultsinstead ofself.nodes. Runninginfrahubctl generator --listfollowed by a dry-run will confirm.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/docs/guides/generator.mdx (3)
2-8: Drop the redundant H1 headingDocusaurus already renders the page title from the front-matter. Keeping the explicit
# How to create a generator in Infrahubresults in two visually identical titles. Delete the Markdown heading or, if you prefer keeping it, remove thetitle:field from the front-matter to avoid duplication.
35-40: Tighten wording to avoid “locally” repetitionBullet 4 starts with “The repository cloned locally …” immediately after bullet 3 ends with “configured locally”. Consider re-phrasing bullet 4 to drop the second “locally” (e.g. “A clone of the repository where you’ll develop the generator”).
319-337: Minor polish in code snippet
- The loop variable
countshadows the outerwidget_countconcept and reads awkwardly (for count in range(1, widget_count + 1)). Renaming it toioridximproves clarity.- Using
self.nodes[0]assumes the query always returns exactly one node. A safer pattern is to iterate overself.nodesor explicitly check length to avoid index errors when the generator is repurposed.Example diff:
- widget = self.nodes[0] + if not self.nodes: + return + widget = self.nodes[0] ... - for count in range(1, widget_count + 1): + for idx in range(1, widget_count + 1): ... - "name": f"{widget_name.lower()}-{count}", + "name": f"{widget_name.lower()}-{idx}",
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/docs/guides/generator.mdx(2 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
docs/docs/guides/**/*.{md,mdx}
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Write guides in
docs/docs/guides/
Files:
docs/docs/guides/generator.mdx
docs/**/*.mdx
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Use Docusaurus markdown/MDX features in documentation
Files:
docs/docs/guides/generator.mdx
docs/**/*
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Develop documentation in
docs/, preview withinvoke docs.build docs.serve, and validate withinvoke docs.validate
Files:
docs/docs/guides/generator.mdx
🪛 LanguageTool
docs/docs/guides/generator.mdx
[style] ~40-~40: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...figured locally - The repository cloned locally where you'll develop the generator ## ...
(ADVERB_REPETITION_PREMIUM)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: validate-generated-documentation
- GitHub Check: documentation
🔇 Additional comments (1)
docs/docs/guides/generator.mdx (1)
345-360: Double-check.infrahub.ymlsemantics
targets: widgetsexpects the group ID rather than the display name. If the group ID differs from the literal string"widgets"(for example, it is auto-generated or namespaced), the generator will never match. Please verify the exact group identifier in Infrahub and adjust if necessary.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
docs/docs/guides/generator copy.mdx (2)
41-46: Remove the double “locally” to satisfy Vale and improve readability- [infrahubctl]($(base_url)infrahubctl/infrahubctl) installed and configured locally - The repository cloned locally where you'll develop the generator + [infrahubctl]($(base_url)infrahubctl/infrahubctl) installed and configured + A local clone of the repository where you’ll develop the generator
325-343: Example code usesself.nodes, which is not part of the publicInfrahubGeneratorAPIUnless you have a subclass that injects
self.nodes, this will raiseAttributeError.
Typical access patterns are:for edge in data["TestWidget"]["edges"]: widget = edge["node"]or, if the SDK provides a typed helper:
widget = self.store.get(widget_id)Please verify the existence of
self.nodesor update the example accordingly.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/docs/guides/generator copy.mdx(1 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
docs/docs/guides/**/*.{md,mdx}
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Write guides in
docs/docs/guides/
Files:
docs/docs/guides/generator copy.mdx
docs/**/*.mdx
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Use Docusaurus markdown/MDX features in documentation
Files:
docs/docs/guides/generator copy.mdx
docs/**/*
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Develop documentation in
docs/, preview withinvoke docs.build docs.serve, and validate withinvoke docs.validate
Files:
docs/docs/guides/generator copy.mdx
🪛 LanguageTool
docs/docs/guides/generator copy.mdx
[style] ~46-~46: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...figured locally - The repository cloned locally where you'll develop the generator ## ...
(ADVERB_REPETITION_PREMIUM)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: documentation
- GitHub Check: validate-generated-documentation
- GitHub Check: Cloudflare Pages
🔇 Additional comments (2)
docs/docs/guides/generator copy.mdx (2)
351-366: Parameter key mismatches the GraphQL variable nameThe GraphQL query declares a variable
$name, but the generator definition passesname__value. Unless there is implicit mapping, the variable will benullat runtime.- parameters: - name: "name__value" + parameters: + name: "name"Double-check the infrahubctl parameter-substitution rules and adjust either the query or the YAML accordingly.
9-11: Ensure$(base_url)is actually expanded or switch to a real URLI couldn’t find any Docusaurus config or plugin that would replace the
$(base_url)placeholder at build time. If you’re relying on a custom remark/rehype plugin make sure it’s registered in yourdocusaurus.config.js(or wherever you configure MDX plugins). Otherwise the link will render literally and break.Please verify one of the following:
- You have a plugin in your Docusaurus config that replaces
$(base_url)with the site’s base URL.- If not, update the link in
docs/docs/guides/generator copy.mdx(lines 9–11) to a relative or absolute URL, for example:[infrahubctl generator](/infrahubctl/infrahubctl-generator)
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/docs/guides/generator.mdx (1)
35-41: Avoid repetitive wording in prerequisites list.The word “locally” appears twice in consecutive bullet points, which reads awkwardly (“… installed and configured locally” / “The repository cloned locally…”).
Streamline the sentence to improve flow, e.g.:- - [infrahubctl]($(base_url)infrahubctl/infrahubctl) installed and configured locally - - The repository cloned locally where you'll develop the generator + - [infrahubctl]($(base_url)infrahubctl/infrahubctl) installed and configured on your machine + - A local clone of the repository where you'll develop the generator
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/docs/guides/generator.mdx(2 hunks)
🧰 Additional context used
📓 Path-based instructions (3)
docs/docs/guides/**/*.{md,mdx}
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Write guides in
docs/docs/guides/
Files:
docs/docs/guides/generator.mdx
docs/**/*.mdx
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Use Docusaurus markdown/MDX features in documentation
Files:
docs/docs/guides/generator.mdx
docs/**/*
📄 CodeRabbit Inference Engine (.github/copilot-instructions.md)
Develop documentation in
docs/, preview withinvoke docs.build docs.serve, and validate withinvoke docs.validate
Files:
docs/docs/guides/generator.mdx
🪛 LanguageTool
docs/docs/guides/generator.mdx
[style] ~40-~40: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...figured locally - The repository cloned locally where you'll develop the generator ## ...
(ADVERB_REPETITION_PREMIUM)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: documentation
- GitHub Check: validate-generated-documentation
🔇 Additional comments (2)
docs/docs/guides/generator.mdx (2)
122-140: Schema snippet omits data-type metadata for numeric attribute.
countis declared askind: Numberwithout specifyingnumber_kind(e.g.,Integer,Float) which the schema validator usually expects. Readers copying this snippet may hit validation errors.Add the explicit subtype:
- - name: count - kind: Number + - name: count + kind: Number + number_kind: Integer
346-356: Parameter mapping in.infrahub.ymlmay not line up with CLI usage.The generator calls are shown as positional arguments (
name=widget1), but the YAML defines:parameters: name: "name__value"Depending on the current spec,
parametersis either:
- A list of objects (
- name: ... path: ...) or- A mapping under
variables:.Please verify the expected structure; if the CLI fails to substitute, readers will be blocked at “Step 5”.
This pull request updates the documentation prompt to align with the Diátaxis framework, and fully refreshes the generator guide accordingly.
Key improvements made to follow the documentation guidelines include:
Summary by CodeRabbit